home *** CD-ROM | disk | FTP | other *** search
/ Your Choice 3 / Your Choice Software Collection 3.iso / prgmming / xlib41 / readme.doc < prev    next >
Text File  |  1994-08-25  |  20KB  |  374 lines
  1. ******************************************************************************
  2. Quick Start with XLIB
  3. ******************************************************************************
  4.  
  5.      The user manual is largely dedicated to cover specifics of XLIB which will
  6. not be of concern to many programmers.  A few notes are added here to expedite 
  7. matters for these programmers.
  8.      If you are not an assembly language programmer, then consider using EASYX 
  9. rather than XLIB.  EASYX does not require use or knowledge of assembly 
  10. language.  The documentation for EASYX is in the file EASYX.DOC.
  11.      If you are familiar with assembly language, then start by reading the file
  12. DONTREAD.ME.  This file is for those who don't particularly enjoy reading 60 
  13. page user manuals.  It is an excellent tutorial.  You will probably be ready 
  14. to program with XLIB after working through the tutorial.
  15.  
  16. ******************************************************************************
  17. A Note to Previous XLIB Users
  18. ******************************************************************************
  19.  
  20.      Version 4.1 is the sixth generation of XLIB.  We appreciate those who have
  21. labored with us through earlier generations when we were stomping several
  22. bugs and correcting deficiencies.  
  23.      Thanks to your patience and help, XLIB is now a solid product.  It is
  24. presently being used in several high tech industries.  We feel that XLIB is
  25. the easiest way available to program in protected mode under DOS, and it 
  26. remains far less expensive than retail DOS extenders.
  27.  
  28.                                                                                                          TechniLib
  29.  
  30. ******************************************************************************
  31. Registering XLIB
  32. ******************************************************************************
  33.  
  34.      XLIB may be registered for $40/copy.  Registrants will be sent a registered
  35. copy of the XLIB archive along with a printed copy of the user manual.  The
  36. registration fee is $60 for those who have used or intend to use technical
  37. support.  The additional charges do not pertain to those reporting problems
  38. with XLIB.
  39.      There are three ways to register XLIB:
  40.  
  41. 1) By credit card through Public (software) Library:
  42.  
  43.      You can order with MC, Visa, Amex, or Discover from Public (software)
  44. Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398
  45. or by CIS Email to 71355,470.  You can also mail credit card orders to PsL
  46. at P.O.Box 35705, Houston, TX 77235-5705.  The product identification number 
  47. for XLIB is 11077.
  48.  
  49. PHONE NUMBERS ABOVE ARE FOR ORDERS ONLY.  Any questions about the status of 
  50. the shipment of the order, refunds, registration options, product details, 
  51. technical support, volume discounts, dealer pricing, site licenses, etc, 
  52. should NOT be directed to PsL.  Direct all such questions to TechniLib.
  53.  
  54. 2) Through CompuServe:
  55.      
  56.      Use GO SWREG (shareware registration).  The program identification number 
  57. is 1778.  The program title is XLIB 4.1.
  58.  
  59. 3) By mail to TechniLib:
  60.  
  61.      Complete and mail the form in REGISTER.FRM
  62.  
  63. ******************************************************************************
  64. Improvements in XLIB Version 4.1 Over Version 4.0
  65. ******************************************************************************
  66.  
  67.      Version 4.1 is minor upgrade.  The exception handler under version 4.0
  68. did not properly manage keypresses.  This problem has been corrected in
  69. version 4.1.  A minor bug has also been corrected in DONTREAD.ME.
  70.  
  71. ******************************************************************************
  72. Upgrades
  73. ******************************************************************************
  74.      
  75.      Previous registrants can upgrade to XLIB version 4.1 for $10.  Send
  76. all such orders directly to TechniLib.  Registrants to version 4.0 may
  77. upgrade to version 4.1 at no charge.  Simply run the program PATCH4.EXE
  78. and follow the instructions it provides.
  79.  
  80. ******************************************************************************
  81. Communicating with TechniLib Via Electronic Mail
  82. ******************************************************************************
  83.  
  84.      You can communicate with TechniLib via CompuServe electronic mail.  Direct
  85. mail to account 74730,167.  
  86.  
  87. ******************************************************************************
  88. Instructions for Constructing Protected-Mode Libraries for Microsoft
  89. ******************************************************************************
  90.  
  91.      The following batch file uses Microsoft LIB to combine an OBJ file with
  92. XLIB.LIB to produce a protected-mode library.  Call the batch file using the
  93. base name of the OBJ file as the argument.  This base name will also be given
  94. to the library.  It is assumed that the OBJ file and XLIB.LIB are in the
  95. current directory.  LIB.EXE is assumed to be in the ..\BIN directory.
  96.  
  97. @echo on
  98. del %1.lib
  99. ..\bin\lib %1.lib /noi +%1.obj+xlib.lib;
  100.  
  101.      The following batch file uses Microsoft LINK and LIB to combine an OBJ
  102. file with XLIB.LIB to produce a protected-mode library and quick library for
  103. Microsoft BASIC 7.0.  Call the batch file using the base name of the OBJ
  104. file as the argument.  This base name will also be given to the library and
  105. the quick library.  It is assumed that all files apart from LINK.EXE and
  106. LIB.EXE are in the current directory.  The current directory must also
  107. contain the file QBXQLB.LIB (included in the BASIC distribution disks).
  108. LINK.EXE and LIB.EXE are assumed to be in the ..\BIN directory.
  109.  
  110. @echo on
  111. del %1.qlb
  112. del %1.lib
  113. ..\bin\link /q/nopackf xlib.lib+%1.obj,%1.qlb,,qbxqlb.lib;
  114. ..\bin\lib %1.lib +xlib.lib+%1.obj;
  115.  
  116.      The following command may be used to create a quick library from EASYX.LIB.
  117. The quick library is called EASYX.QLB:
  118.  
  119. ..\bin\link /q/nopackf easyx.lib,easyx.qlb,,qbxqlb.lib;
  120.  
  121. ******************************************************************************
  122. Instructions for Constructing Libraries and Linking with Borland
  123. ******************************************************************************
  124.      
  125.      The following batch file uses TLINK to link an OBJ file from TASM with
  126. XLIBB.LIB to produce a DOS-extended executable.  The base name of the OBJ
  127. is supplied as an argument to the batch file.  The executable will be given 
  128. the same base name as the OBJ file.  It is assumed that the OBJ file is in 
  129. the current directory and that TLINK is in the ..\BIN directory.
  130.  
  131. @echo on
  132. ..\bin\tlink /3/c %1.obj,,,xlibb.lib
  133.  
  134.      The following batch file uses Borland TLIB to combine an OBJ file with
  135. XLIBB.LIB to produce a protected-mode library.  Call the batch file using the
  136. base name of the OBJ file as the argument.  This base name will also be given
  137. to the library.  It is assumed that XLIBB.LIB and the OBJ file are in the 
  138. current directory.  TLIB is assumed to be in the ..\BIN directory.
  139.  
  140. @echo on
  141. del %1.lib
  142. ..\bin\tlib /C %1.lib +xlibb.lib+%1.obj
  143.  
  144.      Borland C and Turbo C users can compile within the IDE; however, they must
  145. use the command line linker because an option will be needed which is not
  146. included in the IDE linker.  In particular, the /3 option will be needed to
  147. enable processing of 32-bit segments.  The appropriate commands to TLINK will
  148. depend upon the memory model being used.  The following batch command will 
  149. link a program called MYPROG with a library call MYLIB under the large memory 
  150. model.  The batch command must be issued from the directory containing 
  151. MYPROG.OBJ.  It is assumed that TLINK is in the ..\BIN directory and that
  152. MYLIB.LIB is in the ..\LIB directory.  It is also assumed that all of the C 
  153. link libraries are in the ..\LIB directory.  The resulting executable will be 
  154. called MYPROG.EXE and the map file will be called MYPROG.MAP.  The command 
  155. line is lengthy and is therefore broken into two lines below.
  156.  
  157.  
  158.                                                      --------------------- model specification
  159.                                                      .   ----------------- obj file name
  160.                                                      .   |      ---------- exe file name
  161.                                                      .   |      |      --- map file name
  162.                                                      . ______ ______ ______
  163. ..\bin\tlink /3/c ..\lib\c0l myprog,myprog,myprog,
  164.  
  165.      ..\lib\mylib ..\lib\fp87 ..\lib\mathl ..\lib\cl 
  166.                     -----                        .         .
  167.                         |                          -------------- model specification
  168.                         ----------------------------------------- lib file name
  169.  
  170. To link under the small memory model, replace "l" with "s" at the model
  171. specification characters.  Use "m" for the medium model; "c" for the compact
  172. model, and "h" for the huge model.
  173.  
  174. ******************************************************************************
  175. NOEMS and Equivalent Options
  176. ******************************************************************************
  177.  
  178.      Numerous of you could never get previous versions of XLIB initialized
  179. because you were running your memory managers with the NOEMS or equivalent 
  180. option.  This problem should be corrected under version 4.1, but we suggest
  181. that you avoid NOEMS.  If you want the upper memory area used by the page
  182. frame than try FRAME=NONE or equivalent option.
  183.      When EMS is present, VCPI has control of the machine.  This means that
  184. XLIB must work cooperatively with VCPI when performing switches to protected
  185. mode; otherwise, XLIB would cause a protection violation (exception #13).
  186. VCPI is a subset of EMS.  When you declared NOEMS, it appeared to former 
  187. version of XLIB that VCPI was absent.  The latter assumption was false, 
  188. because the memory manager was hiding VCPI behind the NOEMS option.  XLIB 
  189. then proceeded to perform uncooperative mode switches.  This then generated 
  190. the exception.  Version 4.1 takes measures to detect a deceptive memory 
  191. manager.
  192.  
  193. ******************************************************************************
  194. General Debugging Instructions
  195. ******************************************************************************
  196.  
  197.      Neither Turbo Debugger nor Codeview will be able to debug protected-mode
  198. instructions.  However, you should still be able to use the debuggers for
  199. real-mode areas of your programs.  Just step over calls to protected-mode
  200. procedures.
  201.      Debuggers tend to have problems when XLIB is initialized for DPMI.  Use
  202. VCPI instead.  You do this by setting bit 0 of IFLAGS.  Of course, a VCPI 
  203. driver needs to be loaded.  EMM386, QEMM386, and 386MAX all have VCPI.  You 
  204. cannot run VCPI in Windows or OS/2.
  205.      In the event that you can debug under DPMI, then you will have to remember
  206. that XLIBE and XLIBEB attempt to trap exceptions in real mode, including
  207. debug exceptions and breakpoints.  You better turn these features off by 
  208. setting bit 1 of IFLAGS.  This disables all exception trapping and prevents
  209. remap of hardware interrupts.
  210.      Be sure to read the documentation about the new debugging functions in
  211. XLIBE.LIB and XLIBEB.LIB.  These can be used in protected mode.  The new
  212. exception handlers are going to make life much easier also.
  213.  
  214. ******************************************************************************
  215. Instructions for Debugging in the Borland IDE
  216. ******************************************************************************
  217.  
  218.      To run the IDE debugger, XLIB should be initialized for VCPI.  However,
  219. under the default behavior of the IDE, a VCPI program will not be able to
  220. allocate extended memory within the IDE.  There are potentially two reasons 
  221. for this.  First, the default behavior of the DPMI kernel under which the 
  222. IDE operates is to claim all EMS memory and convert it to DPMI memory.  
  223. Since VCPI seeks extended memory through EMS, no extended memory will appear 
  224. to be available.  To limit the memory consumption of the DPMI kernel, 
  225. include a statement such as the following in the batch file used to invoke 
  226. the IDE:
  227.  
  228. set dpmimem=maxmem 2000
  229.  
  230. This statement limits the memory usage of the DPMI kernel to 2000Kb.  If
  231. EMS memory exceeds this amount, then EMS memory will be available to the 
  232. IDE.  However, EMS memory will not be available to a VCPI program running 
  233. within the IDE if the IDE has itself consumed all EMS memory.  Therefore, 
  234. one may have to limit EMS memory usage of the IDE.  This can be done in the 
  235. OPTIONS|ENVIRONMENT|STARTUP menu of the IDE.  Typically, EMS memory usage
  236. should be set to zero here.
  237.  
  238. ******************************************************************************
  239. Known Bugs/Peculiarities in Memory Managers
  240. ******************************************************************************
  241.  
  242. 1) All versions of QDPMI appear to map physical address spaces incorrectly.
  243.      The actual mapping call will succeed; however, this call affects QDPMI
  244.      internally such that subsequent calls to allocate extended memory do not
  245.      function correctly.  This means that MAPIO and PMMAPIO will not work
  246.      reliably with QDPMI.
  247.  
  248. 2) Version 1.03 of QDPMI does not handle exceptions properly.  The exception
  249.      handler receives the wrong value for the interrupted SS on the stack.
  250.      As a consequence, XLIB will not be able to terminate a program after an
  251.      exception under this version of QDPMI.  Reboot will be necessary.  This
  252.      problem may also exist in previous versions.
  253.  
  254. 3) QDPMI apparently does not function properly when the NOEMS option has been
  255.      used on QEMM.  NOEMS typically should not be used with any memory manager.
  256.      If you need the space normally allocated to the EMS page frame, then set
  257.      FRAME=NONE (or equivalent option) instead of using NOEMS.
  258.  
  259. 4) 386MAX versions 6.X and 7.0 leave interrupts disabled after calls to
  260.      certain VCPI memory management functions.  This means that when VCPI is
  261.      being used, interrupts will be disabled after calls to PMGETMEM, PMFREEMEM,
  262.      PMRESETMEM, and PMMAPIO.
  263.  
  264. 5) 386MAX version 7.0 does not properly report the virtual debug status
  265.      register (virtual DR6) upon debug exceptions.  Consequently, the DR6
  266.      value presented by the XLIBE exception handler will not be valid.  This
  267.      version also fails to clear debug breakpoints upon termination, as required
  268.      of DPMI 1.0 hosts.  XLIBE corrects the latter problem by clearing
  269.      breakpoints itself when terminating.
  270.  
  271. 6) 386MAX version 7.0 apparently mismanages exception #13 from real mode.
  272.      When the XLIBE exception handler attempts to terminate after such 
  273.      exceptions, a second exception #13 occurs.  This has not proven to be a
  274.      major problem.  Simply ignore the second exception.
  275.  
  276.      386MAX version 7.01 apparently corrects all of the above problems found
  277. in version 7.0.  Qualitas has made a patch available to implement these
  278. corrections.  Download the patch from the Qualitas BBS (301-907-8030).  The
  279. patch for 386MAX is M701R.ZIP.  The patch for BlueMax is B701R.ZIP.
  280.      
  281. ******************************************************************************
  282. Real-Mode Exception Trapping with DPMI Version 1.0 
  283. ******************************************************************************
  284.  
  285.      DPMI 1.0 enables XLIBE to trap exception in real mode.  This makes XLIBE
  286. potentially useful to programmers who would otherwise have no interest in
  287. protected-mode programming.  Simply place a call to INITXLIB early in your
  288. program and link with XLIBE.LIB (XLIBEB.LIB for Borland users) to implement
  289. this feature.
  290.      386MAX version 7.X is the only DPMI 1.0 host of which we are presently 
  291. aware.  Version 7.01 is an outstanding product.
  292.  
  293. ******************************************************************************
  294. Contracted Programming and Consultation
  295. ******************************************************************************
  296.  
  297.      TechniLib will perform contract programming at competitive rates.
  298. TechniLib will also serve as a consultant to other programmers.  Contact
  299. TechniLib through the channels presented above.
  300.  
  301. ******************************************************************************
  302. Improvements in XLIB Version 2.0 Over Version 1.0
  303. ******************************************************************************
  304.  
  305. 1) Procedures enabling protected-mode programming in C using inline assembly.
  306. 2) Protected-mode file routines which can transfer extended memory to files 
  307.      or files to extended memory.  Sequential and random access are supported.
  308. 3) Better interrupt management services.
  309. 4) User-defined descriptors.
  310. 5) More descriptors.  
  311. 6) More configurability.
  312. 7) Minor bug fixes
  313. 8) Better documentation.
  314.  
  315. ******************************************************************************
  316. Improvements in XLIB Version 3.0 Over Version 2.0
  317. ******************************************************************************
  318.  
  319. 1) Files included in Borland formats.
  320. 2) EASYX library included for those unfamiliar with assembly langauge.
  321. 3) MAPIO and PMMAPIO procedures added to XLIB for accessing memory-mapped 
  322.      input/output devices.
  323. 4) Better documentation
  324.  
  325. ******************************************************************************
  326. Improvements in XLIB Version 4.0 Over Version 3.0
  327. ******************************************************************************
  328.  
  329. Additions:
  330.  
  331.      The principal improvement in version 4.0 is the inclusion of libraries
  332. with exception trapping capabilities.  XLIB 4.0 can trap all protected-mode
  333. exceptions.  If DPMI 1.0 is installed, then real-mode exceptions can be
  334. trapped as well.  These libraries also contain new functions for managing
  335. debug watchpoints.
  336.      XLIB 3.0 was limited in that it did not allow the main program to spawn
  337. other processes.  This limitation has been corrected.
  338.      The global descriptor table has been made public in version 4.0.  
  339.      PMPRINT.ASM has been replaced with PMIO.INC.  The latter contains better
  340. print routines as well as new keyboard and speaker routines.  PMIO.INC is
  341. designed for either MASM or TASM.
  342.      The MOVMEM routine in EASYX has been redesigned to be faster and to be
  343. reentrant.  This routine may now be called in the main thread, in interrupt
  344. handlers, or both.
  345.      Microsoft BASIC 7.0 files have been included to illustrate usage of EASYX.
  346.  
  347. Corrections:
  348.  
  349.      Version 4.0 corrects certain bugs and makes accommodations for anomalies
  350. in BIOS and common resident software.
  351.      The most severe bug in version 3.0 was a mistake in the include file
  352. XLIB.INC.  The combine type on segment DSEG was set to FAR_DATA, whereas it
  353. should have been DATA.
  354.      A second bug caused the machine to crash with a call to INITXLIB when
  355. certain memory managers were used with the NOEMS option.
  356.      Version 3.0 did not preserve the interrupt flag through mode switches.
  357. Instead it always enabled interrupts after the switch.  This lead to awkward
  358. situations when attempting to use SWITCHPM and SWITCHRM in interrupt handlers.
  359. Version 4.0 always preserves the interrupt flag through a mode switch.
  360.      A bug prevented SWITCHPM and SWITCHRM from being reentrant under VCPI.
  361. This bug existed in both versions 3.0 and 3.1.  This would have caused a
  362. problem if nested mode switches were being performed, as would be the case
  363. with calls to DEFLECTPM or other mode switches within interrupt handlers.
  364.      Certain versions of SMARTDRV.EXE do not restore the global descriptor
  365. table register.  Version 3.0 was not prepared for this
  366.      Certain BIOS software interrupts return with interrupts enabled.  Neither
  367. version 3.0 nor version 3.1 were prepared for this anomaly.  It caused the
  368. machine to hang upon certain hardware interrupts, keypresses in particular.
  369.      The other bugs were applicable only when running XLIB in the absence of
  370. VCPI and DPMI (HIMEM.SYS only or no memory manager at all).  Accesses to
  371. extended memory failed in some cases.  In some cases the machine was left in
  372. an unstable state.
  373.  
  374.